home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dbdsqr.z / dbdsqr
Encoding:
Text File  |  2002-10-03  |  7.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))                                                          DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DBDSQR - compute the singular value decomposition (SVD) of a real N-by-N
  10.      (upper or lower) bidiagonal matrix B
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE DBDSQR( UPLO, N, NCVT, NRU, NCC, D, E, VT, LDVT, U, LDU, C,
  14.                         LDC, WORK, INFO )
  15.  
  16.          CHARACTER      UPLO
  17.  
  18.          INTEGER        INFO, LDC, LDU, LDVT, N, NCC, NCVT, NRU
  19.  
  20.          DOUBLE         PRECISION C( LDC, * ), D( * ), E( * ), U( LDU, * ),
  21.                         VT( LDVT, * ), WORK( * )
  22.  
  23. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  24.      These routines are part of the SCSL Scientific Library and can be loaded
  25.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  26.      directs the linker to use the multi-processor version of the library.
  27.  
  28.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  29.      4 bytes (32 bits). Another version of SCSL is available in which integers
  30.      are 8 bytes (64 bits).  This version allows the user access to larger
  31.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  32.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  33.      only one of the two versions; 4-byte integer and 8-byte integer library
  34.      calls cannot be mixed.
  35.  
  36. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  37.      DBDSQR computes the singular value decomposition (SVD) of a real N-by-N
  38.      (upper or lower) bidiagonal matrix B: B = Q * S * P' (P' denotes the
  39.      transpose of P), where S is a diagonal matrix with non-negative diagonal
  40.      elements (the singular values of B), and Q and P are orthogonal matrices.
  41.  
  42.      The routine computes S, and optionally computes U * Q, P' * VT, or Q' *
  43.      C, for given real input matrices U, VT, and C.
  44.  
  45.      See "Computing  Small Singular Values of Bidiagonal Matrices With
  46.      Guaranteed High Relative Accuracy," by J. Demmel and W. Kahan, LAPACK
  47.      Working Note #3 (or SIAM J. Sci. Statist. Comput. vol. 11, no. 5, pp.
  48.      873-912, Sept 1990) and
  49.      "Accurate singular values and differential qd algorithms," by B. Parlett
  50.      and V. Fernando, Technical Report CPAM-554, Mathematics Department,
  51.      University of California at Berkeley, July 1992 for a detailed
  52.      description of the algorithm.
  53.  
  54.  
  55. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  56.      UPLO    (input) CHARACTER*1
  57.              = 'U':  B is upper bidiagonal;
  58.              = 'L':  B is lower bidiagonal.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))                                                          DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      N       (input) INTEGER
  75.              The order of the matrix B.  N >= 0.
  76.  
  77.      NCVT    (input) INTEGER
  78.              The number of columns of the matrix VT. NCVT >= 0.
  79.  
  80.      NRU     (input) INTEGER
  81.              The number of rows of the matrix U. NRU >= 0.
  82.  
  83.      NCC     (input) INTEGER
  84.              The number of columns of the matrix C. NCC >= 0.
  85.  
  86.      D       (input/output) DOUBLE PRECISION array, dimension (N)
  87.              On entry, the n diagonal elements of the bidiagonal matrix B.  On
  88.              exit, if INFO=0, the singular values of B in decreasing order.
  89.  
  90.      E       (input/output) DOUBLE PRECISION array, dimension (N)
  91.              On entry, the elements of E contain the offdiagonal elements of
  92.              the bidiagonal matrix whose SVD is desired. On normal exit (INFO
  93.              = 0), E is destroyed.  If the algorithm does not converge (INFO >
  94.              0), D and E will contain the diagonal and superdiagonal elements
  95.              of a bidiagonal matrix orthogonally equivalent to the one given
  96.              as input. E(N) is used for workspace.
  97.  
  98.      VT      (input/output) DOUBLE PRECISION array, dimension (LDVT, NCVT)
  99.              On entry, an N-by-NCVT matrix VT.  On exit, VT is overwritten by
  100.              P' * VT.  VT is not referenced if NCVT = 0.
  101.  
  102.      LDVT    (input) INTEGER
  103.              The leading dimension of the array VT.  LDVT >= max(1,N) if NCVT
  104.              > 0; LDVT >= 1 if NCVT = 0.
  105.  
  106.      U       (input/output) DOUBLE PRECISION array, dimension (LDU, N)
  107.              On entry, an NRU-by-N matrix U.  On exit, U is overwritten by U *
  108.              Q.  U is not referenced if NRU = 0.
  109.  
  110.      LDU     (input) INTEGER
  111.              The leading dimension of the array U.  LDU >= max(1,NRU).
  112.  
  113.      C       (input/output) DOUBLE PRECISION array, dimension (LDC, NCC)
  114.              On entry, an N-by-NCC matrix C.  On exit, C is overwritten by Q'
  115.              * C.  C is not referenced if NCC = 0.
  116.  
  117.      LDC     (input) INTEGER
  118.              The leading dimension of the array C.  LDC >= max(1,N) if NCC >
  119.              0; LDC >=1 if NCC = 0.
  120.  
  121.      WORK    (workspace) DOUBLE PRECISION array, dimension (4*N)
  122.  
  123.      INFO    (output) INTEGER
  124.              = 0:  successful exit
  125.              < 0:  If INFO = -i, the i-th argument had an illegal value
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))                                                          DDDDBBBBDDDDSSSSQQQQRRRR((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              > 0:  the algorithm did not converge; D and E contain the
  141.              elements of a bidiagonal matrix which is orthogonally similar to
  142.              the input matrix B;  if INFO = i, i elements of E have not
  143.              converged to zero.
  144.  
  145. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  146.      TOLMUL  DOUBLE PRECISION, default = max(10,min(100,EPS**(-1/8)))
  147.              TOLMUL controls the convergence criterion of the QR loop.  If it
  148.              is positive, TOLMUL*EPS is the desired relative precision in the
  149.              computed singular values.  If it is negative,
  150.              abs(TOLMUL*EPS*sigma_max) is the desired absolute accuracy in the
  151.              computed singular values (corresponds to relative accuracy
  152.              abs(TOLMUL*EPS) in the largest singular value.  abs(TOLMUL)
  153.              should be between 1 and 1/EPS, and preferably between 10 (for
  154.              fast convergence) and .1/EPS (for there to be some accuracy in
  155.              the results).  Default is to lose at either one eighth or 2 of
  156.              the available decimal digits in each computed singular value
  157.              (whichever is smaller).
  158.  
  159.      MAXITR  INTEGER, default = 6
  160.              MAXITR controls the maximum number of passes of the algorithm
  161.              through its inner loop. The algorithms stops (and so fails to
  162.              converge) if the number of passes through the inner loop exceeds
  163.              MAXITR*N**2.
  164.  
  165. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  166.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  167.  
  168.      This man page is available only online.
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.